<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- firststepsqml.qdoc -->
  <title>First Steps with QML | Qt 5.12 5.12.3</title>
  <link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
  <script type="text/javascript">
    document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
    // loading style sheet breaks anchors that were jumped to before
    // so force jumping to anchor again
    setTimeout(function() {
        var anchor = location.hash;
        // need to jump to different anchor first (e.g. none)
        location.hash = "#";
        setTimeout(function() {
            location.hash = anchor;
        }, 0);
    }, 0);
  </script>
</head>
<body>
<div class="header" id="qtdocheader">
  <div class="main">
    <div class="main-rounded">
      <div class="navigationbar">
        <table><tr>
<td ><a href="index.html">Qt 5.12</a></td><td >First Steps with QML</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.12.3 参考指南</td>
        </tr></table>
      </div>
    </div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">目录</a></h3>
<ul>
<li class="level1"><a href="#creating-a-qml-document">创建QML文档</a></li>
<li class="level2"><a href="#importing-and-using-the-qtquick-module">导入和使用QtQuick模块</a></li>
<li class="level2"><a href="#defining-an-object-hierarchy">定义对象层次结构</a></li>
<li class="level2"><a href="#putting-it-all-together">导入与声明一起使用</a></li>
<li class="level1"><a href="#creating-and-running-qml-projects">创建和运行QML项目</a></li>
<li class="level1"><a href="#creating-qml-applications-with-controls">使用控件创建QML应用程序</a></li>
<li class="level1"><a href="#handling-user-input">处理用户输入</a></li>
<li class="level1"><a href="#property-bindings">属性绑定</a></li>
<li class="level1"><a href="#animations">动画</a></li>
<li class="level1"><a href="#defining-custom-qml-types-for-re-use">定义可重用的自定义QML类型</a></li>
<li class="level1"><a href="#where-to-go-from-here">我们接下来去哪？</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">迈出QML的第一步</h1>
<span class="subtitle"></span>
<!-- $$$qmlfirststeps.html-description -->
<div class="descr"> <a name="details"></a>
<a name="creating-a-qml-document"></a>
<h2 id="creating-a-qml-document">创建QML文档</h2>
<p>QML文档定义了具有高度可读的结构化布局的对象层次结构。每个QML文档由两部分组成:导入部分和对象声明部分。用户界面最常见的类型和功能在<code>QtQuick</code>导入中提供。</p>
<a name="importing-and-using-the-qtquick-module"></a>
<h3 >导入和使用QtQuick模块</h3>
<p>要使用<a href="../qtquick/qtquick-index.html">Qt Quick</a>模块，需要导入QML文档。导入语法如下:</p>
<pre class="cpp">

  import <span class="type"><a href="../qtqml/qtquick-qmlmodule.html">QtQuick</a></span> <span class="number">2.3</span>

</pre>
<p><a href="../qtquick/qtquick-index.html">Qt Quick</a>提供的类型和功能现在可以在QML文档中使用!</p>
<a name="defining-an-object-hierarchy"></a>
<h3 >Defining an Object Hierarchy（定义对象层次结构）</h3>
<p>QML文档中的对象声明定义了可视场景中显示的内容。<a href="../qtquick/qtquick-index.html">Qt Quick</a>为所有用户界面提供了基本的构建块，例如用于显示图像和文本以及处理用户输入的对象。</p>
<p>一个简单的对象声明可以是一个有颜色的矩形，其中可以有一些居中的文本:</p>
<pre class="qml">

  <span class="type"><a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a></span> {
      <span class="name">width</span>: <span class="number">200</span>
      <span class="name">height</span>: <span class="number">100</span>
      <span class="name">color</span>: <span class="string">&quot;red&quot;</span>

      <span class="type"><a href="../qtquick/qml-qtquick-text.html">Text</a></span> {
          <span class="name">anchors</span>.centerIn: <span class="name">parent</span>
          <span class="name">text</span>: <span class="string">&quot;Hello, World!&quot;</span>
      }
  }

</pre>
<p>这定义了一个对象层次结构，其中包含一个具有子<a href="../qtquick/qml-qtquick-text.html">Text（文本）</a>对象的根<a href="../qtquick/qml-qtquick-rectangle.html">Rectangle（矩形）</a>对象。<a href="../qtquick/qml-qtquick-text.html">Text</a>的<code>父对象</code>被自动设置为<a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a>，也可以说，<a href="../qtquick/qml-qtquick-text.html">Text</a> 被QML添加到<a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a>对象的<code>children（子）</code>属性中了。</p>
<a name="putting-it-all-together"></a>
<h3 >导入与声明一起使用</h3>
<p>上面示例中使用的<a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a> 和 <a href="../qtquick/qml-qtquick-text.html">Text</a> 类型都由 <code>QtQuick</code>导入提供。将导入和对象声明放在一起，我们得到了一个完整的QML文档:</p>
<pre class="qml">

  import QtQuick 2.3

  <span class="type"><a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a></span> {
      <span class="name">width</span>: <span class="number">200</span>
      <span class="name">height</span>: <span class="number">100</span>
      <span class="name">color</span>: <span class="string">&quot;red&quot;</span>

      <span class="type"><a href="../qtquick/qml-qtquick-text.html">Text</a></span> {
          <span class="name">anchors</span>.centerIn: <span class="name">parent</span>
          <span class="name">text</span>: <span class="string">&quot;Hello, World!&quot;</span>
      }
  }

</pre>
<p>如果我们将该文档保存为&quot;HelloWorld.qml&quot;，我们可以加载和显示它。</p>
<a name="creating-and-running-qml-projects"></a>
<h2 id="creating-and-running-qml-projects">创建和运行QML项目</h2>
<p>要显示QML文档定义的图形化场景，可以使用<a href="http://doc.qt.io/qtcreator/index.html">Qt Creator</a>加载它。对于像这样的简单UI文件，在Qt Creator中。 <b>File &gt; New File or Project &gt; Applications &gt; Qt Quick UI</b>。</p>
<p>按下绿色<b>Run</b>按钮运行应用程序。你会在红色的矩形看到<b>Hello, World!</b>。</p>
<p>有关在Qt Creator中创建和运行项目的更多信息，请访问以下页面:</p>
<ul>
<li><a href="http://doc.qt.io/qtcreator/quick-projects.html">创建Qt Quick项目</a></li>
<li><a href="http://doc.qt.io/qtcreator/creator-build-example-application.html">构建并运行一个示例</a></li>
</ul>
<a name="creating-qml-applications-with-controls"></a>
<h2 id="creating-qml-applications-with-controls">使用控件创建QML应用程序</h2>
<p>Qt Quick提供基本的图形元素， <a href="../qtquickcontrols/qtquickcontrols-index.html">Qt Quick 控件</a>提供现成的QML类型供应用程序使用。</p>
<p>插入<a href="../qtquickcontrols/qml-qtquick-controls2-applicationwindow.html">ApplicationWindow</a>类型是创建应用程序的良好起点。应用程序UI的基本布局如下:</p>
<p class="centerAlign"><img src="images/applicationwindow.png" alt="" /></p><p>在每个区域内，可以添加和连接不同的<i>controls（控件）</i> 来形成应用程序。例如，下面的代码片段是一个演示如何使用可用空间的基本应用程序:</p>
<pre class="qml">

  <span class="comment">//import related modules</span>
  import QtQuick 2.12
  import QtQuick.Controls 2.12

  <span class="comment">//window containing the application</span>
  <span class="type"><a href="../qtquickcontrols/qml-qtquick-controls2-applicationwindow.html">ApplicationWindow</a></span> {

      <span class="comment">//title of the application</span>
      <span class="name">title</span>: <span class="name">qsTr</span>(<span class="string">&quot;Hello World&quot;</span>)
      <span class="name">width</span>: <span class="number">640</span>
      <span class="name">height</span>: <span class="number">480</span>

      <span class="comment">//menu containing two menu items</span>
      <span class="name">menuBar</span>: <span class="name">MenuBar</span> {
          <span class="type"><a href="../qtquickcontrols/qml-qtquick-controls2-menu.html">Menu</a></span> {
              <span class="name">title</span>: <span class="name">qsTr</span>(<span class="string">&quot;File&quot;</span>)
              <span class="type"><a href="../qtquickcontrols/qml-qtquick-controls2-menuitem.html">MenuItem</a></span> {
                  <span class="name">text</span>: <span class="name">qsTr</span>(<span class="string">&quot;&amp;Open&quot;</span>)
                  <span class="name">onTriggered</span>: <span class="name">console</span>.<span class="name">log</span>(<span class="string">&quot;Open action triggered&quot;</span>);
              }
              <span class="type"><a href="../qtquickcontrols/qml-qtquick-controls2-menuitem.html">MenuItem</a></span> {
                  <span class="name">text</span>: <span class="name">qsTr</span>(<span class="string">&quot;Exit&quot;</span>)
                  <span class="name">onTriggered</span>: <span class="name">Qt</span>.<span class="name">quit</span>();
              }
          }
      }

      <span class="comment">//Content Area</span>

      <span class="comment">//a button in the middle of the content area</span>
      <span class="type"><a href="../qtquickcontrols/qml-qtquick-controls2-button.html">Button</a></span> {
          <span class="name">text</span>: <span class="name">qsTr</span>(<span class="string">&quot;Hello World&quot;</span>)
          <span class="name">anchors</span>.horizontalCenter: <span class="name">parent</span>.<span class="name">horizontalCenter</span>
          <span class="name">anchors</span>.verticalCenter: <span class="name">parent</span>.<span class="name">verticalCenter</span>
      }
  }

</pre>
<p>应用程序有两个菜单项和一个按钮在中间。单击<b>Exit</b>菜单项将关闭应用程序。</p>
<p>还有不同的导航方法和不同的控件，如按钮和滑块。以下示例可从Qt Creator获得，并演示了不同的控件和布局。</p>
<ul>
<li><a href="../qtquick/qtquick-layouts-example.html">基本布局</a></li>
<li><a href="../qtquickcontrols/qtquickcontrols-gallery-example.html">Qt Quick 控件 - Gallery（画廊）</a></li>
</ul>
<p>您可以随意复制并粘贴这些代码片段到这个简单的Hellow World应用程序上，以了解QML是如何工作的。</p>
<a name="handling-user-input"></a>
<h2 id="handling-user-input">处理用户输入</h2>
<p>使用QML定义用户界面的一大优点是，它允许用户界面设计人员使用简单的JavaScript表达式定义应用程序应该如何响应事件。在QML中，我们将这些事件称为<a href="../qtqml/qtqml-syntax-signals.html">signals（信号）</a>  <a href="../qtqml/qtqml-syntax-signals.html#qml-signals-and-handlers"></a>，这些信号由信号处理程序处理</p>
<p>例如，思考下面的例子:</p>
<pre class="qml">

  import QtQuick 2.12

  <span class="type"><a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a></span> {
      <span class="name">width</span>: <span class="number">200</span>
      <span class="name">height</span>: <span class="number">100</span>
      <span class="name">color</span>: <span class="string">&quot;red&quot;</span>

      <span class="type"><a href="../qtquick/qml-qtquick-text.html">Text</a></span> {
          <span class="name">anchors</span>.centerIn: <span class="name">parent</span>
          <span class="name">text</span>: <span class="string">&quot;Hello, World!&quot;</span>
      }

      <span class="type"><a href="../qtquick/qml-qtquick-taphandler.html">TapHandler</a></span> {
          <span class="name">onTapped</span>: <span class="name">parent</span>.<span class="name">color</span> <span class="operator">=</span> <span class="string">&quot;blue&quot;</span>
      }
  }

</pre>
<p>这个例子可以保存为&quot;ClickableHelloWorld.qml&quot; 并用qmlscene运行。 每当用户单击窗口中的任何位置时，矩形将从红色变为蓝色。</p>
<p><b>注意: </b><a href="../qtquick/qml-qtquick-taphandler.html">TapHandler</a> 还为触摸事件发出被敲击的信号，所以这段代码也可以在移动设备上工作。</p><p>键盘用户输入同样可以用一个简单的表达式来处理:</p>
<pre class="qml">

  <span class="type"><a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a></span> {
      <span class="name">width</span>: <span class="number">200</span>
      <span class="name">height</span>: <span class="number">100</span>
      <span class="name">color</span>: <span class="string">&quot;red&quot;</span>

      <span class="type"><a href="../qtquick/qml-qtquick-text.html">Text</a></span> {
          <span class="name">anchors</span>.centerIn: <span class="name">parent</span>
          <span class="name">text</span>: <span class="string">&quot;Hello, World!&quot;</span>
      }

      <span class="name">focus</span>: <span class="number">true</span>
      <span class="name">Keys</span>.onPressed: {
          <span class="keyword">if</span> (<span class="name">event</span>.<span class="name">key</span> <span class="operator">==</span> <span class="name">Qt</span>.<span class="name">Key_Return</span>) {
              <span class="name">color</span> <span class="operator">=</span> <span class="string">&quot;blue&quot;</span>;
              <span class="name">event</span>.<span class="name">accepted</span> <span class="operator">=</span> <span class="number">true</span>;
          }
      }
  }

</pre>
<p>通过接受焦点，只要按下返回键，颜色就可以变为蓝色。 </p>
<a name="property-bindings"></a>
<h2 id="property-bindings">属性绑定</h2>
<p>对象及其属性构成了在QML文档中定义的图形界面的基础。QML语言允许属性以各种方式相互绑定，从而实现高度动态的用户界面。</p>
<p>在下面的示例中，每个子<a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a>的几何形状都绑定到父<a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a>如果要更改父<a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a> 矩形的几何图形，则由于属性绑定，每个子  <a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a>的几何图形将自动更新。</p>
<pre class="qml">

  <span class="type"><a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a></span> {
      <span class="name">width</span>: <span class="number">400</span>
      <span class="name">height</span>: <span class="number">200</span>

      <span class="type"><a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a></span> {
          <span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span> <span class="operator">/</span> <span class="number">2</span>
          <span class="name">height</span>: <span class="name">parent</span>.<span class="name">height</span>
      }

      <span class="type"><a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a></span> {
          <span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span> <span class="operator">/</span> <span class="number">2</span>
          <span class="name">height</span>: <span class="name">parent</span>.<span class="name">height</span>
          <span class="name">x</span>: <span class="name">parent</span>.<span class="name">width</span> <span class="operator">/</span> <span class="number">2</span>
      }
  }

</pre>
<a name="animations"></a>
<h2 id="animations">动画</h2>
<p>属性也可以通过动画动态更新。<code>QtQuick</code>导入提供了各种动画类型，可用于对属性值的更改进行动画处理。在下面的例子中，一个属性被动画化，然后显示在<a href="../qtquick/qml-qtquick-text.html">Text（文本类）</a> 区域中:</p>
<pre class="qml">

  <span class="type"><a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a></span> {
      <span class="name">color</span>: <span class="string">&quot;lightgray&quot;</span>
      <span class="name">width</span>: <span class="number">200</span>
      <span class="name">height</span>: <span class="number">200</span>

      property <span class="type"><a href="../qtqml/qml-int.html">int</a></span> <span class="name">animatedValue</span>: <span class="number">0</span>
      SequentialAnimation on <span class="name">animatedValue</span> {
          <span class="name">loops</span>: <span class="name">Animation</span>.<span class="name">Infinite</span>
          <span class="type"><a href="../qtquick/qml-qtquick-propertyanimation.html">PropertyAnimation</a></span> { <span class="name">to</span>: <span class="number">150</span>; <span class="name">duration</span>: <span class="number">1000</span> }
          <span class="type"><a href="../qtquick/qml-qtquick-propertyanimation.html">PropertyAnimation</a></span> { <span class="name">to</span>: <span class="number">0</span>; <span class="name">duration</span>: <span class="number">1000</span> }
      }

      <span class="type"><a href="../qtquick/qml-qtquick-text.html">Text</a></span> {
          <span class="name">anchors</span>.centerIn: <span class="name">parent</span>
          <span class="name">text</span>: <span class="name">parent</span>.<span class="name">animatedValue</span>
      }
  }

</pre>
<p>所显示的值将周期性地从0变化到150。</p>
<a name="defining-custom-qml-types-for-re-use"></a>
<h2 id="defining-custom-qml-types-for-re-use">定义可重用的自定义QML类型</h2>
<p>QML中最重要的概念之一是类型重用。一个应用程序可能有多个相似的可视类型(例如，多个按钮)，</p>
<p>例如，假设开发人员在 <code>MessageLabel.qml</code>文件中定义了一个新的MessageLabel类型，如下：</p>
<pre class="qml">

  <span class="comment">// MessageLabel.qml</span>
  import QtQuick 2.12

  <span class="type"><a href="../qtquick/qml-qtquick-rectangle.html">Rectangle</a></span> {
      <span class="name">height</span>: <span class="number">50</span>
      property <span class="type"><a href="../qtqml/qml-string.html">string</a></span> <span class="name">message</span>: <span class="string">&quot;debug message&quot;</span>
      property <span class="type"><a href="../qtqml/qml-var.html">var</a></span> <span class="name">msgType</span>: [<span class="string">&quot;debug&quot;</span>, <span class="string">&quot;warning&quot;</span> , <span class="string">&quot;critical&quot;</span>]
      <span class="name">color</span>: <span class="string">&quot;black&quot;</span>

      <span class="type"><a href="../qtquick/qml-qtquick-column.html">Column</a></span> {
          <span class="name">anchors</span>.fill: <span class="name">parent</span>
          <span class="name">padding</span>: <span class="number">5.0</span>
          <span class="name">spacing</span>: <span class="number">2</span>
          <span class="type"><a href="../qtquick/qml-qtquick-text.html">Text</a></span> {
              <span class="name">text</span>: <span class="name">msgType</span>.<span class="name">toString</span>().<span class="name">toUpperCase</span>() <span class="operator">+</span> <span class="string">&quot;:&quot;</span>
              <span class="name">font</span>.bold: <span class="name">msgType</span> <span class="operator">==</span> <span class="string">&quot;critical&quot;</span>
              <span class="name">font</span>.family: <span class="string">&quot;Terminal Regular&quot;</span>
              <span class="name">color</span>: <span class="name">msgType</span> <span class="operator">===</span> <span class="string">&quot;warning&quot;</span> <span class="operator">||</span> <span class="name">msgType</span> <span class="operator">===</span> <span class="string">&quot;critical&quot;</span> ? <span class="string">&quot;red&quot;</span> : <span class="string">&quot;yellow&quot;</span>
              ColorAnimation on <span class="name">color</span> {
                  <span class="name">running</span>: <span class="name">msgType</span> <span class="operator">==</span> <span class="string">&quot;critical&quot;</span>
                  <span class="name">from</span>: <span class="string">&quot;red&quot;</span>
                  <span class="name">to</span>: <span class="string">&quot;black&quot;</span>
                  <span class="name">duration</span>: <span class="number">1000</span>
                  <span class="name">loops</span>: <span class="name">msgType</span> <span class="operator">==</span> <span class="string">&quot;critical&quot;</span> ? <span class="name">Animation</span>.<span class="name">Infinite</span> : <span class="number">1</span>
              }
          }
          <span class="type"><a href="../qtquick/qml-qtquick-text.html">Text</a></span> {
              <span class="name">text</span>: <span class="name">message</span>
              <span class="name">color</span>: <span class="name">msgType</span> <span class="operator">===</span> <span class="string">&quot;warning&quot;</span> <span class="operator">||</span> <span class="name">msgType</span> <span class="operator">===</span> <span class="string">&quot;critical&quot;</span> ? <span class="string">&quot;red&quot;</span> : <span class="string">&quot;yellow&quot;</span>
              <span class="name">font</span>.family: <span class="string">&quot;Terminal Regular&quot;</span>
          }
      }

  }

</pre>
<p>该类型现在可以在应用程序中重用多次，如下所示:</p>
<div class="table"><table class="generic">
 <tr valign="top" class="odd"><td ><pre class="qml">

  <span class="comment">// application.qml</span>
  import QtQuick 2.12

  <span class="type"><a href="../qtquick/qml-qtquick-column.html">Column</a></span> {
      <span class="name">width</span>: <span class="number">180</span>
      <span class="name">height</span>: <span class="number">180</span>
      <span class="name">padding</span>: <span class="number">1.5</span>
      <span class="name">topPadding</span>: <span class="number">10.0</span>
      <span class="name">bottomPadding</span>: <span class="number">10.0</span>
      <span class="name">spacing</span>: <span class="number">5</span>

      <span class="type">MessageLabel</span>{
          <span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span> <span class="operator">-</span> <span class="number">2</span>
          <span class="name">msgType</span>: <span class="string">&quot;debug&quot;</span>
      }
      <span class="type">MessageLabel</span> {
          <span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span> <span class="operator">-</span> <span class="number">2</span>
          <span class="name">message</span>: <span class="string">&quot;This is a warning!&quot;</span>
          <span class="name">msgType</span>: <span class="string">&quot;warning&quot;</span>
      }
      <span class="type">MessageLabel</span> {
          <span class="name">width</span>: <span class="name">parent</span>.<span class="name">width</span> <span class="operator">-</span> <span class="number">2</span>
          <span class="name">message</span>: <span class="string">&quot;A critical warning!&quot;</span>
          <span class="name">msgType</span>: <span class="string">&quot;critical&quot;</span>
      }
  }

</pre>
</td><td ><div class="border"><p class="centerAlign"><img src="images/qml-extending-types.gif" alt="" /></p></div></td></tr>
</table></div>
<p>通过这种方式，模块化的用户界面类型在应用程序中被组装和重用。</p>
<p>有关如何开发自己的可重用组件的详细信息，请参阅<a href="../qtqml/qtqml-syntax-objectattributes.html">QML Object Attributes（QML对象属性）</a></p>
<a name="where-to-go-from-here"></a>
<h2 id="where-to-go-from-here">我们接下来去哪？</h2>
<p>现在您已经看到QML的作用，您已经准备好进行下一步。接下来的页面将带领您踏上QML之旅。</p>
<ul>
<li><a href="qmlapplications.html">QML应用程序</a></li>
<li><a href="qtexamplesandtutorials.html">Qt示例和教程</a></li>
</ul>
</div>
<!-- @@@qmlfirststeps.html -->
        </div>
       </div>
   </div>
   </div>
</div>
<div class="footer">
   <p>
   <acronym title="Copyright">&copy;</acronym> 2019 The Qt Company Ltd.
   Documentation contributions included herein are the copyrights of
   their respective owners.<br/>    The documentation provided herein is licensed under the terms of the    <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation    License version 1.3</a> as published by the Free Software Foundation.<br/>    Qt and respective logos are trademarks of The Qt Company Ltd.     in Finland and/or other countries worldwide. All other trademarks are property
   of their respective owners. </p>
</div>
</body>
</html>
